org.springframework.jms.core

Class JmsTemplate

java.lang.Object

org.springframework.jms.support.JmsAccessor

org.springframework.jms.support.destination.JmsDestinationAccessor

org.springframework.jms.core.JmsTemplate

All Implemented Interfaces:

InitializingBean, JmsOperations

public class JmsTemplate
extends JmsDestinationAccessor
implements JmsOperations

Helper class that simplifies synchronous JMS access code.

If you want to use dynamic destination creation, you must specify the type of JMS destination to create, using the "pubSubDomain" property. For other operations, this is not necessary. Point-to-Point (Queues) is the default domain.

Default settings for JMS Sessions are "not transacted" and "auto-acknowledge". As defined by the J2EE specification, the transaction and acknowledgement parameters are ignored when a JMS Session is created inside an active transaction, no matter if a JTA transaction or a Spring-managed transaction. To configure them for native JMS usage, specify appropriate values for the "sessionTransacted" and "sessionAcknowledgeMode" bean properties.

This template uses a DynamicDestinationResolver and a SimpleMessageConverter as default strategies for resolving a destination name or converting a message, respectively. These defaults can be overridden through the "destinationResolver" and "messageConverter" bean properties.

NOTE: The ConnectionFactory used with this template should return pooled Connections (or a single shared Connection) as well as pooled Sessions and MessageProducers. Otherwise, performance of ad-hoc JMS operations is going to suffer. The simplest option is to use the Spring-provided SingleConnectionFactory as a decorator for your target ConnectionFactory, reusing a single JMS Connection in a thread-safe fashion; this is often good enough for the purpose of sending messages via this template. In a J2EE environment, make sure that the ConnectionFactory is obtained from the application's environment naming context via JNDI; application servers typically expose pooled, transaction-aware factories there.

Since:

1.1

Author:

Mark Pollack, Juergen Hoeller, Stephane Nicoll

See Also:

JmsAccessor.setConnectionFactory(ConnectionFactory), JmsDestinationAccessor.setPubSubDomain(boolean), JmsDestinationAccessor.setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver), setMessageConverter(org.springframework.jms.support.converter.MessageConverter), javax.jms.MessageProducer, javax.jms.MessageConsumer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	JmsTemplate.JmsTemplateResourceFactory ResourceFactory implementation that delegates to this template's protected callback methods.

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.Object	defaultDestination
private long	deliveryDelay
private int	deliveryMode
private boolean	explicitQosEnabled
private MessageConverter	messageConverter
private boolean	messageIdEnabled
private boolean	messageTimestampEnabled
private int	priority
private boolean	pubSubNoLocal
static long	RECEIVE_TIMEOUT_INDEFINITE_WAIT Timeout value indicating a blocking receive without timeout.
static long	RECEIVE_TIMEOUT_NO_WAIT Timeout value indicating that a receive operation should check if a message is immediately available without blocking.
private long	receiveTimeout
private static java.lang.reflect.Method	setDeliveryDelayMethod
private long	timeToLive
private JmsTemplate.JmsTemplateResourceFactory	transactionalResourceFactory Internal ResourceFactory adapter for interacting with ConnectionFactoryUtils

Fields inherited from class org.springframework.jms.support.JmsAccessor

logger

Constructor Summary

Constructors

Constructor and Description
JmsTemplate() Create a new JmsTemplate for bean-style usage.
JmsTemplate(ConnectionFactory connectionFactory) Create a new JmsTemplate, given a ConnectionFactory.

Method Summary

Modifier and Type	Method and Description
<T> T	browse(BrowserCallback<T> action) Browse messages in the default JMS queue.
<T> T	browse(Queue queue, BrowserCallback<T> action) Browse messages in a JMS queue.
<T> T	browseSelected(Queue queue, java.lang.String messageSelector, BrowserCallback<T> action) Browse selected messages in a JMS queue.
<T> T	browseSelected(java.lang.String messageSelector, BrowserCallback<T> action) Browse selected messages in a JMS queue.
void	convertAndSend(Destination destination, java.lang.Object message) Send the given object to the specified destination, converting the object to a JMS message with a configured MessageConverter.
void	convertAndSend(Destination destination, java.lang.Object message, MessagePostProcessor postProcessor) Send the given object to the specified destination, converting the object to a JMS message with a configured MessageConverter.
void	convertAndSend(java.lang.Object message) Send the given object to the default destination, converting the object to a JMS message with a configured MessageConverter.
void	convertAndSend(java.lang.Object message, MessagePostProcessor postProcessor) Send the given object to the default destination, converting the object to a JMS message with a configured MessageConverter.
protected QueueBrowser	createBrowser(Session session, Queue queue, java.lang.String messageSelector) Create a JMS MessageProducer for the given Session and Destination, configuring it to disable message ids and/or timestamps (if necessary).
protected MessageConsumer	createConsumer(Session session, Destination destination, java.lang.String messageSelector) Create a JMS MessageConsumer for the given Session and Destination.
protected MessageProducer	createProducer(Session session, Destination destination) Create a JMS MessageProducer for the given Session and Destination, configuring it to disable message ids and/or timestamps (if necessary).
protected java.lang.Object	doConvertFromMessage(Message message) Extract the content from the given JMS message.
protected MessageProducer	doCreateProducer(Session session, Destination destination) Create a raw JMS MessageProducer for the given Session and Destination.
private Message	doReceive(MessageConsumer consumer, long timeout) Actually receive a message from the given consumer.
protected Message	doReceive(Session session, Destination destination, java.lang.String messageSelector) Receive a JMS message.
protected Message	doReceive(Session session, MessageConsumer consumer) Actually receive a JMS message.
protected void	doSend(MessageProducer producer, Message message) Actually send the given JMS message.
protected void	doSend(Session session, Destination destination, MessageCreator messageCreator) Send the given JMS message.
protected Message	doSendAndReceive(Session session, Destination destination, MessageCreator messageCreator) Send a request message to the given Destination and block until a reply has been received on a temporary queue created on-the-fly.
<T> T	execute(Destination destination, ProducerCallback<T> action) Send messages to a JMS destination.
<T> T	execute(ProducerCallback<T> action) Send messages to the default JMS destination (or one specified for each send operation).
<T> T	execute(SessionCallback<T> action) Execute the action specified by the given action object within a JMS Session.
<T> T	execute(SessionCallback<T> action, boolean startConnection) Execute the action specified by the given action object within a JMS Session.
private <T> T	executeLocal(SessionCallback<T> action, boolean startConnection) A variant of execute(SessionCallback, boolean) that explicitly creates a non-transactional Session.
protected Connection	getConnection(JmsResourceHolder holder) Fetch an appropriate Connection from the given JmsResourceHolder.
Destination	getDefaultDestination() Return the destination to be used on send/receive operations that do not have a destination parameter.
java.lang.String	getDefaultDestinationName() Return the destination name to be used on send/receive operations that do not have a destination parameter.
private Queue	getDefaultQueue()
long	getDeliveryDelay() Return the delivery delay to use for send calls (in milliseconds).
int	getDeliveryMode() Return the delivery mode to use when sending a message.
MessageConverter	getMessageConverter() Return the message converter for this template.
int	getPriority() Return the priority of a message when sending.
long	getReceiveTimeout() Return the timeout to use for receive calls (in milliseconds).
private java.lang.String	getRequiredDefaultDestinationName()
private MessageConverter	getRequiredMessageConverter()
protected Session	getSession(JmsResourceHolder holder) Fetch an appropriate Session from the given JmsResourceHolder.
long	getTimeToLive() Return the time-to-live of the message when sending.
protected void	initDefaultStrategies() Initialize the default implementations for the template's strategies: DynamicDestinationResolver and SimpleMessageConverter.
boolean	isExplicitQosEnabled() If "true", then the values of deliveryMode, priority, and timeToLive will be used when sending a message.
boolean	isMessageIdEnabled() Return whether message IDs are enabled.
boolean	isMessageTimestampEnabled() Return whether message timestamps are enabled.
boolean	isPubSubNoLocal() Return whether to inhibit the delivery of messages published by its own connection.
protected boolean	isSessionLocallyTransacted(Session session) Check whether the given Session is locally transacted, that is, whether its transaction is managed by this listener container's Session handling and not by an external transaction coordinator.
Message	receive() Receive a message synchronously from the default destination, but only wait up to a specified time for delivery.
Message	receive(Destination destination) Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.
Message	receive(java.lang.String destinationName) Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.
java.lang.Object	receiveAndConvert() Receive a message synchronously from the default destination, but only wait up to a specified time for delivery.
java.lang.Object	receiveAndConvert(Destination destination) Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.
Message	receiveSelected(Destination destination, java.lang.String messageSelector) Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.
Message	receiveSelected(java.lang.String messageSelector) Receive a message synchronously from the default destination, but only wait up to a specified time for delivery.
Message	receiveSelected(java.lang.String destinationName, java.lang.String messageSelector) Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.
java.lang.Object	receiveSelectedAndConvert(Destination destination, java.lang.String messageSelector) Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.
java.lang.Object	receiveSelectedAndConvert(java.lang.String messageSelector) Receive a message synchronously from the default destination, but only wait up to a specified time for delivery.
void	send(Destination destination, MessageCreator messageCreator) Send a message to the specified destination.
void	send(MessageCreator messageCreator) Send a message to the default destination.
Message	sendAndReceive(Destination destination, MessageCreator messageCreator) Send a message and receive the reply from the specified destination.
Message	sendAndReceive(MessageCreator messageCreator) Send a request message and receive the reply from a default destination.
Message	sendAndReceive(java.lang.String destinationName, MessageCreator messageCreator) Send a message and receive the reply from the specified destination.
void	setDefaultDestination(Destination destination) Set the destination to be used on send/receive operations that do not have a destination parameter.
void	setDefaultDestinationName(java.lang.String destinationName) Set the destination name to be used on send/receive operations that do not have a destination parameter.
void	setDeliveryDelay(long deliveryDelay) Set the delivery delay to use for send calls (in milliseconds).
void	setDeliveryMode(int deliveryMode) Set the delivery mode to use when sending a message.
void	setDeliveryPersistent(boolean deliveryPersistent) Set whether message delivery should be persistent or non-persistent, specified as boolean value ("true" or "false").
void	setExplicitQosEnabled(boolean explicitQosEnabled) Set if the QOS values (deliveryMode, priority, timeToLive) should be used for sending a message.
void	setMessageConverter(MessageConverter messageConverter) Set the message converter for this template.
void	setMessageIdEnabled(boolean messageIdEnabled) Set whether message IDs are enabled.
void	setMessageTimestampEnabled(boolean messageTimestampEnabled) Set whether message timestamps are enabled.
void	setPriority(int priority) Set the priority of a message when sending.
void	setPubSubNoLocal(boolean pubSubNoLocal) Set whether to inhibit the delivery of messages published by its own connection.
void	setReceiveTimeout(long receiveTimeout) Set the timeout to use for receive calls (in milliseconds).
void	setTimeToLive(long timeToLive) Set the time-to-live of the message when sending.

Methods inherited from class org.springframework.jms.support.destination.JmsDestinationAccessor

getDestinationResolver, isPubSubDomain, resolveDestinationName, setDestinationResolver, setPubSubDomain

Methods inherited from class org.springframework.jms.support.JmsAccessor

afterPropertiesSet, convertJmsAccessException, createConnection, createSession, getConnectionFactory, getSessionAcknowledgeMode, isClientAcknowledge, isSessionTransacted, setConnectionFactory, setSessionAcknowledgeMode, setSessionAcknowledgeModeName, setSessionTransacted

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RECEIVE_TIMEOUT_NO_WAIT

public static final long RECEIVE_TIMEOUT_NO_WAIT

Timeout value indicating that a receive operation should check if a message is immediately available without blocking.

See Also:

Constant Field Values

RECEIVE_TIMEOUT_INDEFINITE_WAIT

public static final long RECEIVE_TIMEOUT_INDEFINITE_WAIT

Timeout value indicating a blocking receive without timeout.

See Also:

Constant Field Values

setDeliveryDelayMethod

private static final java.lang.reflect.Method setDeliveryDelayMethod

transactionalResourceFactory

private final JmsTemplate.JmsTemplateResourceFactory transactionalResourceFactory

Internal ResourceFactory adapter for interacting with ConnectionFactoryUtils

defaultDestination

private java.lang.Object defaultDestination

messageConverter

private MessageConverter messageConverter

messageIdEnabled

private boolean messageIdEnabled

messageTimestampEnabled

private boolean messageTimestampEnabled

pubSubNoLocal

private boolean pubSubNoLocal

receiveTimeout

private long receiveTimeout

deliveryDelay

private long deliveryDelay

explicitQosEnabled

private boolean explicitQosEnabled

deliveryMode

private int deliveryMode

priority

private int priority

timeToLive

private long timeToLive

Constructor Detail

JmsTemplate

public JmsTemplate()

Create a new JmsTemplate for bean-style usage.

Note: The ConnectionFactory has to be set before using the instance. This constructor can be used to prepare a JmsTemplate via a BeanFactory, typically setting the ConnectionFactory via setConnectionFactory.

See Also:

JmsAccessor.setConnectionFactory(ConnectionFactory)

JmsTemplate

public JmsTemplate(ConnectionFactory connectionFactory)

Create a new JmsTemplate, given a ConnectionFactory.

Parameters:

connectionFactory - the ConnectionFactory to obtain Connections from

Method Detail

initDefaultStrategies

protected void initDefaultStrategies()

Initialize the default implementations for the template's strategies: DynamicDestinationResolver and SimpleMessageConverter.

See Also:

JmsDestinationAccessor.setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver), setMessageConverter(org.springframework.jms.support.converter.MessageConverter), DynamicDestinationResolver, SimpleMessageConverter

setDefaultDestination

public void setDefaultDestination(Destination destination)

Set the destination to be used on send/receive operations that do not have a destination parameter.

Alternatively, specify a "defaultDestinationName", to be dynamically resolved via the DestinationResolver.

See Also:

send(MessageCreator), convertAndSend(Object), convertAndSend(Object, MessagePostProcessor), setDefaultDestinationName(String)

getDefaultDestination

public Destination getDefaultDestination()

Return the destination to be used on send/receive operations that do not have a destination parameter.

getDefaultQueue

private Queue getDefaultQueue()

setDefaultDestinationName

public void setDefaultDestinationName(java.lang.String destinationName)

Set the destination name to be used on send/receive operations that do not have a destination parameter. The specified name will be dynamically resolved via the DestinationResolver.

Alternatively, specify a JMS Destination object as "defaultDestination".

See Also:

send(MessageCreator), convertAndSend(Object), convertAndSend(Object, MessagePostProcessor), JmsDestinationAccessor.setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver), #setDefaultDestination(javax.jms.Destination)

getDefaultDestinationName

public java.lang.String getDefaultDestinationName()

Return the destination name to be used on send/receive operations that do not have a destination parameter.

getRequiredDefaultDestinationName

private java.lang.String getRequiredDefaultDestinationName()
                                                    throws java.lang.IllegalStateException

Throws:

java.lang.IllegalStateException

setMessageConverter

public void setMessageConverter(MessageConverter messageConverter)

Set the message converter for this template. Used to resolve Object parameters to convertAndSend methods and Object results from receiveAndConvert methods.

The default converter is a SimpleMessageConverter, which is able to handle BytesMessages, TextMessages and ObjectMessages.

See Also:

convertAndSend(java.lang.Object), receiveAndConvert(), SimpleMessageConverter

getMessageConverter

public MessageConverter getMessageConverter()

Return the message converter for this template.

getRequiredMessageConverter

private MessageConverter getRequiredMessageConverter()
                                              throws java.lang.IllegalStateException

Throws:

java.lang.IllegalStateException

setMessageIdEnabled

public void setMessageIdEnabled(boolean messageIdEnabled)

Set whether message IDs are enabled. Default is "true".

This is only a hint to the JMS producer. See the JMS javadocs for details.

See Also:

javax.jms.MessageProducer#setDisableMessageID

isMessageIdEnabled

public boolean isMessageIdEnabled()

Return whether message IDs are enabled.

setMessageTimestampEnabled

public void setMessageTimestampEnabled(boolean messageTimestampEnabled)

Set whether message timestamps are enabled. Default is "true".

This is only a hint to the JMS producer. See the JMS javadocs for details.

See Also:

javax.jms.MessageProducer#setDisableMessageTimestamp

isMessageTimestampEnabled

public boolean isMessageTimestampEnabled()

Return whether message timestamps are enabled.

setPubSubNoLocal

public void setPubSubNoLocal(boolean pubSubNoLocal)

Set whether to inhibit the delivery of messages published by its own connection. Default is "false".

See Also:

javax.jms.Session#createConsumer(javax.jms.Destination, String, boolean)

isPubSubNoLocal

public boolean isPubSubNoLocal()

Return whether to inhibit the delivery of messages published by its own connection.

setReceiveTimeout

public void setReceiveTimeout(long receiveTimeout)

Set the timeout to use for receive calls (in milliseconds).

The default is RECEIVE_TIMEOUT_INDEFINITE_WAIT, which indicates a blocking receive without timeout.

Specify RECEIVE_TIMEOUT_NO_WAIT to inidicate that a receive operation should check if a message is immediately available without blocking.

See Also:

javax.jms.MessageConsumer#receive(long), javax.jms.MessageConsumer#receive(), javax.jms.MessageConsumer#receiveNoWait()

getReceiveTimeout

public long getReceiveTimeout()

Return the timeout to use for receive calls (in milliseconds).

setDeliveryDelay

public void setDeliveryDelay(long deliveryDelay)

Set the delivery delay to use for send calls (in milliseconds).

The default is 0 (no delivery delay). Note that this feature requires JMS 2.0.

getDeliveryDelay

public long getDeliveryDelay()

Return the delivery delay to use for send calls (in milliseconds).

setExplicitQosEnabled

public void setExplicitQosEnabled(boolean explicitQosEnabled)

Set if the QOS values (deliveryMode, priority, timeToLive) should be used for sending a message.

See Also:

setDeliveryMode(int), setPriority(int), setTimeToLive(long)

isExplicitQosEnabled

public boolean isExplicitQosEnabled()

If "true", then the values of deliveryMode, priority, and timeToLive will be used when sending a message. Otherwise, the default values, that may be set administratively, will be used.

Returns:

true if overriding default values of QOS parameters (deliveryMode, priority, and timeToLive)

See Also:

setDeliveryMode(int), setPriority(int), setTimeToLive(long)

setDeliveryPersistent

public void setDeliveryPersistent(boolean deliveryPersistent)

Set whether message delivery should be persistent or non-persistent, specified as boolean value ("true" or "false"). This will set the delivery mode accordingly, to either "PERSISTENT" (2) or "NON_PERSISTENT" (1).

Default is "true" a.k.a. delivery mode "PERSISTENT".

See Also:

setDeliveryMode(int), javax.jms.DeliveryMode#PERSISTENT, javax.jms.DeliveryMode#NON_PERSISTENT

setDeliveryMode

public void setDeliveryMode(int deliveryMode)

Set the delivery mode to use when sending a message. Default is the JMS Message default: "PERSISTENT".

Since a default value may be defined administratively, this is only used when "isExplicitQosEnabled" equals "true".

Parameters:

deliveryMode - the delivery mode to use

See Also:

isExplicitQosEnabled(), javax.jms.DeliveryMode#PERSISTENT, javax.jms.DeliveryMode#NON_PERSISTENT, javax.jms.Message#DEFAULT_DELIVERY_MODE, javax.jms.MessageProducer#send(javax.jms.Message, int, int, long)

getDeliveryMode

public int getDeliveryMode()

Return the delivery mode to use when sending a message.

setPriority

public void setPriority(int priority)

Set the priority of a message when sending.

Since a default value may be defined administratively, this is only used when "isExplicitQosEnabled" equals "true".

See Also:

isExplicitQosEnabled(), javax.jms.Message#DEFAULT_PRIORITY, javax.jms.MessageProducer#send(javax.jms.Message, int, int, long)

getPriority

public int getPriority()

Return the priority of a message when sending.

setTimeToLive

public void setTimeToLive(long timeToLive)

Set the time-to-live of the message when sending.

Since a default value may be defined administratively, this is only used when "isExplicitQosEnabled" equals "true".

Parameters:

timeToLive - the message's lifetime (in milliseconds)

See Also:

isExplicitQosEnabled(), javax.jms.Message#DEFAULT_TIME_TO_LIVE, javax.jms.MessageProducer#send(javax.jms.Message, int, int, long)

getTimeToLive

public long getTimeToLive()

Return the time-to-live of the message when sending.

execute

public <T> T execute(SessionCallback<T> action)
              throws JmsException

Description copied from interface: JmsOperations

Execute the action specified by the given action object within a JMS Session.

Specified by:

execute in interface JmsOperations

Parameters:

action - callback object that exposes the session

Returns:

the result object from working with the session

Throws:

JmsException - if there is any problem

execute

public <T> T execute(SessionCallback<T> action,
                     boolean startConnection)
              throws JmsException

Execute the action specified by the given action object within a JMS Session. Generalized version of execute(SessionCallback), allowing the JMS Connection to be started on the fly.

Use execute(SessionCallback) for the general case. Starting the JMS Connection is just necessary for receiving messages, which is preferably achieved through the receive methods.

Parameters:

action - callback object that exposes the Session

startConnection - whether to start the Connection

Returns:

the result object from working with the Session

Throws:

JmsException - if there is any problem

See Also:

execute(SessionCallback), receive()

execute

public <T> T execute(ProducerCallback<T> action)
              throws JmsException

Description copied from interface: JmsOperations

Send messages to the default JMS destination (or one specified for each send operation). The callback gives access to the JMS Session and MessageProducer in order to perform complex send operations.

Specified by:

execute in interface JmsOperations

Parameters:

action - callback object that exposes the session/producer pair

Returns:

the result object from working with the session

Throws:

JmsException - checked JMSException converted to unchecked

execute

public <T> T execute(Destination destination,
                     ProducerCallback<T> action)
              throws JmsException

Description copied from interface: JmsOperations

Send messages to a JMS destination. The callback gives access to the JMS Session and MessageProducer in order to perform complex send operations.

Specified by:

execute in interface JmsOperations

Parameters:

destination - the destination to send messages to

action - callback object that exposes the session/producer pair

Returns:

the result object from working with the session

Throws:

JmsException - checked JMSException converted to unchecked

send

public void send(MessageCreator messageCreator)
          throws JmsException

Description copied from interface: JmsOperations

Send a message to the default destination.

This will only work with a default destination specified!

Specified by:

send in interface JmsOperations

Parameters:

messageCreator - callback to create a message

Throws:

JmsException - checked JMSException converted to unchecked

send

public void send(Destination destination,
                 MessageCreator messageCreator)
          throws JmsException

Description copied from interface: JmsOperations

Send a message to the specified destination. The MessageCreator callback creates the message given a Session.

Specified by:

send in interface JmsOperations

Parameters:

destination - the destination to send this message to

messageCreator - callback to create a message

Throws:

JmsException - checked JMSException converted to unchecked

doSend

protected void doSend(Session session,
                      Destination destination,
                      MessageCreator messageCreator)
               throws JMSException

Send the given JMS message.

Parameters:

session - the JMS Session to operate on

destination - the JMS Destination to send to

messageCreator - callback to create a JMS Message

Throws:

JMSException - if thrown by JMS API methods

doSend

protected void doSend(MessageProducer producer,
                      Message message)
               throws JMSException

Actually send the given JMS message.

Parameters:

producer - the JMS MessageProducer to send with

message - the JMS Message to send

Throws:

JMSException - if thrown by JMS API methods

convertAndSend

public void convertAndSend(java.lang.Object message)
                    throws JmsException

Description copied from interface: JmsOperations

Send the given object to the default destination, converting the object to a JMS message with a configured MessageConverter.

This will only work with a default destination specified!

Specified by:

convertAndSend in interface JmsOperations

Parameters:

message - the object to convert to a message

Throws:

JmsException - converted checked JMSException to unchecked

convertAndSend

public void convertAndSend(Destination destination,
                           java.lang.Object message)
                    throws JmsException

Description copied from interface: JmsOperations

Send the given object to the specified destination, converting the object to a JMS message with a configured MessageConverter.

Specified by:

convertAndSend in interface JmsOperations

Parameters:

destination - the destination to send this message to

message - the object to convert to a message

Throws:

JmsException - converted checked JMSException to unchecked

convertAndSend

public void convertAndSend(java.lang.Object message,
                           MessagePostProcessor postProcessor)
                    throws JmsException

Description copied from interface: JmsOperations

Send the given object to the default destination, converting the object to a JMS message with a configured MessageConverter. The MessagePostProcessor callback allows for modification of the message after conversion.

This will only work with a default destination specified!

Specified by:

convertAndSend in interface JmsOperations

Parameters:

message - the object to convert to a message

postProcessor - the callback to modify the message

Throws:

JmsException - checked JMSException converted to unchecked

convertAndSend

public void convertAndSend(Destination destination,
                           java.lang.Object message,
                           MessagePostProcessor postProcessor)
                    throws JmsException

Description copied from interface: JmsOperations

Send the given object to the specified destination, converting the object to a JMS message with a configured MessageConverter. The MessagePostProcessor callback allows for modification of the message after conversion.

Specified by:

convertAndSend in interface JmsOperations

Parameters:

destination - the destination to send this message to

message - the object to convert to a message

postProcessor - the callback to modify the message

Throws:

JmsException - checked JMSException converted to unchecked

receive

public Message receive()
                throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the default destination, but only wait up to a specified time for delivery.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

This will only work with a default destination specified!

Specified by:

receive in interface JmsOperations

Returns:

the message received by the consumer, or null if the timeout expires

Throws:

JmsException - checked JMSException converted to unchecked

receive

public Message receive(Destination destination)
                throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

Specified by:

receive in interface JmsOperations

Parameters:

destination - the destination to receive a message from

Returns:

the message received by the consumer, or null if the timeout expires

Throws:

JmsException - checked JMSException converted to unchecked

receive

public Message receive(java.lang.String destinationName)
                throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

Specified by:

receive in interface JmsOperations

Parameters:

destinationName - the destination to receive a message from

Returns:

the message received by the consumer, or null if the timeout expires

Throws:

JmsException - checked JMSException converted to unchecked

receiveSelected

public Message receiveSelected(java.lang.String messageSelector)
                        throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the default destination, but only wait up to a specified time for delivery.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

This will only work with a default destination specified!

Specified by:

receiveSelected in interface JmsOperations

Parameters:

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

Returns:

the message received by the consumer, or null if the timeout expires

Throws:

JmsException - checked JMSException converted to unchecked

receiveSelected

public Message receiveSelected(Destination destination,
                               java.lang.String messageSelector)
                        throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

Specified by:

receiveSelected in interface JmsOperations

Parameters:

destination - the destination to receive a message from

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

Returns:

the message received by the consumer, or null if the timeout expires

Throws:

JmsException - checked JMSException converted to unchecked

receiveSelected

public Message receiveSelected(java.lang.String destinationName,
                               java.lang.String messageSelector)
                        throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

Specified by:

receiveSelected in interface JmsOperations

Parameters:

destinationName - the destination to receive a message from

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

Returns:

the message received by the consumer, or null if the timeout expires

Throws:

JmsException - checked JMSException converted to unchecked

doReceive

protected Message doReceive(Session session,
                            Destination destination,
                            java.lang.String messageSelector)
                     throws JMSException

Receive a JMS message.

Parameters:

session - the JMS Session to operate on

destination - the JMS Destination to receive from

messageSelector - the message selector for this consumer (can be null)

Returns:

the JMS Message received, or null if none

Throws:

JMSException - if thrown by JMS API methods

doReceive

protected Message doReceive(Session session,
                            MessageConsumer consumer)
                     throws JMSException

Actually receive a JMS message.

Parameters:

session - the JMS Session to operate on

consumer - the JMS MessageConsumer to receive with

Returns:

the JMS Message received, or null if none

Throws:

JMSException - if thrown by JMS API methods

doReceive

private Message doReceive(MessageConsumer consumer,
                          long timeout)
                   throws JMSException

Actually receive a message from the given consumer.

Parameters:

consumer - the JMS MessageConsumer to receive with

timeout - the receive timeout

Returns:

the JMS Message received, or null if none

Throws:

JMSException - if thrown by JMS API methods

receiveAndConvert

public java.lang.Object receiveAndConvert()
                                   throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the default destination, but only wait up to a specified time for delivery. Convert the message into an object with a configured MessageConverter.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

This will only work with a default destination specified!

Specified by:

receiveAndConvert in interface JmsOperations

Returns:

the message produced for the consumer or null if the timeout expires.

Throws:

JmsException - checked JMSException converted to unchecked

receiveAndConvert

public java.lang.Object receiveAndConvert(Destination destination)
                                   throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery. Convert the message into an object with a configured MessageConverter.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

Specified by:

receiveAndConvert in interface JmsOperations

Parameters:

destination - the destination to receive a message from

Returns:

the message produced for the consumer or null if the timeout expires.

Throws:

JmsException - checked JMSException converted to unchecked

receiveSelectedAndConvert

public java.lang.Object receiveSelectedAndConvert(java.lang.String messageSelector)
                                           throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the default destination, but only wait up to a specified time for delivery. Convert the message into an object with a configured MessageConverter.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

This will only work with a default destination specified!

Specified by:

receiveSelectedAndConvert in interface JmsOperations

Parameters:

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

Returns:

the message produced for the consumer or null if the timeout expires.

Throws:

JmsException - checked JMSException converted to unchecked

receiveSelectedAndConvert

public java.lang.Object receiveSelectedAndConvert(Destination destination,
                                                  java.lang.String messageSelector)
                                           throws JmsException

Description copied from interface: JmsOperations

Receive a message synchronously from the specified destination, but only wait up to a specified time for delivery. Convert the message into an object with a configured MessageConverter.

This method should be used carefully, since it will block the thread until the message becomes available or until the timeout value is exceeded.

Specified by:

receiveSelectedAndConvert in interface JmsOperations

Parameters:

destination - the destination to receive a message from

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

Returns:

the message produced for the consumer or null if the timeout expires.

Throws:

JmsException - checked JMSException converted to unchecked

doConvertFromMessage

protected java.lang.Object doConvertFromMessage(Message message)

Extract the content from the given JMS message.

Parameters:

message - the JMS Message to convert (can be null)

Returns:

the content of the message, or null if none

sendAndReceive

public Message sendAndReceive(MessageCreator messageCreator)
                       throws JmsException

Description copied from interface: JmsOperations

Send a request message and receive the reply from a default destination. The MessageCreator callback creates the message given a Session. A temporary queue is created as part of this operation and is set in the JMSReplyTO header of the message.

This will only work with a default destination specified!

Specified by:

sendAndReceive in interface JmsOperations

Parameters:

messageCreator - callback to create a request message

Returns:

the reply, possibly null if the message could not be received, for example due to a timeout

Throws:

JmsException - checked JMSException converted to unchecked

sendAndReceive

public Message sendAndReceive(Destination destination,
                              MessageCreator messageCreator)
                       throws JmsException

Description copied from interface: JmsOperations

Send a message and receive the reply from the specified destination. The MessageCreator callback creates the message given a Session. A temporary queue is created as part of this operation and is set in the JMSReplyTO header of the message.

Specified by:

sendAndReceive in interface JmsOperations

Parameters:

destination - the destination to send this message to

messageCreator - callback to create a message

Returns:

the reply, possibly null if the message could not be received, for example due to a timeout

Throws:

JmsException - checked JMSException converted to unchecked

sendAndReceive

public Message sendAndReceive(java.lang.String destinationName,
                              MessageCreator messageCreator)
                       throws JmsException

Description copied from interface: JmsOperations

Send a message and receive the reply from the specified destination. The MessageCreator callback creates the message given a Session. A temporary queue is created as part of this operation and is set in the JMSReplyTO header of the message.

Specified by:

sendAndReceive in interface JmsOperations

Parameters:

destinationName - the destination to send this message to

messageCreator - callback to create a message

Returns:

the reply, possibly null if the message could not be received, for example due to a timeout

Throws:

JmsException - checked JMSException converted to unchecked

doSendAndReceive

protected Message doSendAndReceive(Session session,
                                   Destination destination,
                                   MessageCreator messageCreator)
                            throws JMSException

Send a request message to the given Destination and block until a reply has been received on a temporary queue created on-the-fly.

Return the response message or null if no message has

Throws:

JMSException - if thrown by JMS API methods

executeLocal

private <T> T executeLocal(SessionCallback<T> action,
                           boolean startConnection)
                    throws JmsException

A variant of execute(SessionCallback, boolean) that explicitly creates a non-transactional Session. The given SessionCallback does not participate in an existing transaction.

Throws:

JmsException

browse

public <T> T browse(BrowserCallback<T> action)
             throws JmsException

Description copied from interface: JmsOperations

Browse messages in the default JMS queue. The callback gives access to the JMS Session and QueueBrowser in order to browse the queue and react to the contents.

Specified by:

browse in interface JmsOperations

Parameters:

action - callback object that exposes the session/browser pair

Returns:

the result object from working with the session

Throws:

JmsException - checked JMSException converted to unchecked

browse

public <T> T browse(Queue queue,
                    BrowserCallback<T> action)
             throws JmsException

Description copied from interface: JmsOperations

Browse messages in a JMS queue. The callback gives access to the JMS Session and QueueBrowser in order to browse the queue and react to the contents.

Specified by:

browse in interface JmsOperations

Parameters:

queue - the queue to browse

action - callback object that exposes the session/browser pair

Returns:

the result object from working with the session

Throws:

JmsException - checked JMSException converted to unchecked

browseSelected

public <T> T browseSelected(java.lang.String messageSelector,
                            BrowserCallback<T> action)
                     throws JmsException

Description copied from interface: JmsOperations

Browse selected messages in a JMS queue. The callback gives access to the JMS Session and QueueBrowser in order to browse the queue and react to the contents.

Specified by:

browseSelected in interface JmsOperations

Parameters:

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

action - callback object that exposes the session/browser pair

Returns:

the result object from working with the session

Throws:

JmsException - checked JMSException converted to unchecked

browseSelected

public <T> T browseSelected(Queue queue,
                            java.lang.String messageSelector,
                            BrowserCallback<T> action)
                     throws JmsException

Description copied from interface: JmsOperations

Browse selected messages in a JMS queue. The callback gives access to the JMS Session and QueueBrowser in order to browse the queue and react to the contents.

Specified by:

browseSelected in interface JmsOperations

Parameters:

queue - the queue to browse

messageSelector - the JMS message selector expression (or null if none). See the JMS specification for a detailed definition of selector expressions.

action - callback object that exposes the session/browser pair

Returns:

the result object from working with the session

Throws:

JmsException - checked JMSException converted to unchecked

getConnection

protected Connection getConnection(JmsResourceHolder holder)

Fetch an appropriate Connection from the given JmsResourceHolder.

This implementation accepts any JMS 1.1 Connection.

Parameters:

holder - the JmsResourceHolder

Returns:

an appropriate Connection fetched from the holder, or null if none found

getSession

protected Session getSession(JmsResourceHolder holder)

Fetch an appropriate Session from the given JmsResourceHolder.

This implementation accepts any JMS 1.1 Session.

Parameters:

holder - the JmsResourceHolder

Returns:

an appropriate Session fetched from the holder, or null if none found

isSessionLocallyTransacted

protected boolean isSessionLocallyTransacted(Session session)

Check whether the given Session is locally transacted, that is, whether its transaction is managed by this listener container's Session handling and not by an external transaction coordinator.

Note: The Session's own transacted flag will already have been checked before. This method is about finding out whether the Session's transaction is local or externally coordinated.

Parameters:

session - the Session to check

Returns:

whether the given Session is locally transacted

See Also:

JmsAccessor.isSessionTransacted(), ConnectionFactoryUtils.isSessionTransactional(Session, ConnectionFactory)

createProducer

protected MessageProducer createProducer(Session session,
                                         Destination destination)
                                  throws JMSException

Create a JMS MessageProducer for the given Session and Destination, configuring it to disable message ids and/or timestamps (if necessary).

Delegates to doCreateProducer(Session, Destination) for creation of the raw JMS MessageProducer.

Parameters:

session - the JMS Session to create a MessageProducer for

destination - the JMS Destination to create a MessageProducer for

Returns:

the new JMS MessageProducer

Throws:

JMSException - if thrown by JMS API methods

See Also:

setMessageIdEnabled(boolean), setMessageTimestampEnabled(boolean)

doCreateProducer

protected MessageProducer doCreateProducer(Session session,
                                           Destination destination)
                                    throws JMSException

Create a raw JMS MessageProducer for the given Session and Destination.

This implementation uses JMS 1.1 API.

Parameters:

session - the JMS Session to create a MessageProducer for

destination - the JMS Destination to create a MessageProducer for

Returns:

the new JMS MessageProducer

Throws:

JMSException - if thrown by JMS API methods

createConsumer

protected MessageConsumer createConsumer(Session session,
                                         Destination destination,
                                         java.lang.String messageSelector)
                                  throws JMSException

Create a JMS MessageConsumer for the given Session and Destination.

This implementation uses JMS 1.1 API.

Parameters:

session - the JMS Session to create a MessageConsumer for

destination - the JMS Destination to create a MessageConsumer for

messageSelector - the message selector for this consumer (can be null)

Returns:

the new JMS MessageConsumer

Throws:

JMSException - if thrown by JMS API methods

createBrowser

protected QueueBrowser createBrowser(Session session,
                                     Queue queue,
                                     java.lang.String messageSelector)
                              throws JMSException

Create a JMS MessageProducer for the given Session and Destination, configuring it to disable message ids and/or timestamps (if necessary).

Delegates to doCreateProducer(Session, Destination) for creation of the raw JMS MessageProducer.

Parameters:

session - the JMS Session to create a QueueBrowser for

queue - the JMS Queue to create a QueueBrowser for

messageSelector - the message selector for this consumer (can be null)

Returns:

the new JMS QueueBrowser

Throws:

JMSException - if thrown by JMS API methods

See Also:

setMessageIdEnabled(boolean), setMessageTimestampEnabled(boolean)